import Example from '~/components/example'
import { Code, InlineCode } from '~/components/text/code'
import Link from '~/components/text/link'
import Now from '~/components/text/now'
import {
  InputTable,
  OutputTable,
  Row,
  Cell,
  TypeCell,
  BoldCell,
  BooleanCell
} from '~/components/api/table'
import Endpoint from '~/components/api/endpoint'
import Request from '~/components/api/request'

export const meta = {
  editUrl: 'pages/docs/api/v1/api-docs-mdx/endpoints/domains.mdx',
  lastEdited: '2019-02-16T22:48:11.000Z'
}

## Domains

### List all the domains

<Endpoint method="GET" url="/v2/domains" />

Retrieves a list of domains registered for the authenticating user.
Each domain entry contains an `aliases` array listing every
alias associated with the domain. The field `isExternal` is
a boolean value telling whether an external nameserver is used to
manage DNS records for the domain.

#### Output

<OutputTable>
  <Row>
    <BoldCell>uid</BoldCell>
    <TypeCell>ID</TypeCell>
    <Cell>The unique ID of the domain.</Cell>
  </Row>
  <Row>
    <BoldCell>name</BoldCell>
    <TypeCell>String</TypeCell>
    <Cell>The domain name.</Cell>
  </Row>
  <Row>
    <BoldCell>createdAt</BoldCell>
    <TypeCell>Date</TypeCell>
    <Cell>The date when it was created the registry.</Cell>
  </Row>
  <Row>
    <BoldCell>boughtAt</BoldCell>
    <TypeCell>Date</TypeCell>
    <Cell>
      If it was purchased through {<Now color="#000" />} the date when it was
      purchased.
    </Cell>
  </Row>
  <Row>
    <BoldCell>expiresAt</BoldCell>
    <TypeCell>Date</TypeCell>
    <Cell>
      The date when the domain is going to expire and need to be renewed.
    </Cell>
  </Row>
  <Row>
    <BoldCell>isExternal</BoldCell>
    <TypeCell>Boolean</TypeCell>
    <Cell>
      If it is an{' '}
      <Link href="/docs/getting-started/assign-a-domain-name#4.-using-a-custom-domain-with-a-cname">
        externally handled domain
      </Link>
      .
    </Cell>
  </Row>
  <Row>
    <BoldCell>verified</BoldCell>
    <TypeCell>Boolean</TypeCell>
    <Cell>If the domain has the ownership verified.</Cell>
  </Row>
  <Row>
    <BoldCell>aliases</BoldCell>
    <TypeCell>List</TypeCell>
    <Cell>The list of aliases using the domain.</Cell>
  </Row>
  <Row>
    <BoldCell>certs</BoldCell>
    <TypeCell>List</TypeCell>
    <Cell>
      The list domains or subdomains with a SSL certificated provisioned.
    </Cell>
  </Row>
</OutputTable>

<Example>
  Example request:

<Request
  url="https://api.zeit.co/v2/domains"
  headers={{
    Authorization: `Bearer ${
      props.testingToken ? props.testingToken.token : '$TOKEN'
    }`
  }}
/>

Example successful (**200**) response:

<Code lang="json">{`{
    "domains": [
      {
        "uid": "HVXAOskvQK8ILaF8d8gmwdRx",
        "name": "zeit.rocks",
        "created": "2017-09-03T19:48:50.120Z",
        "boughtAt": "2017-09-03T19:48:46.000Z",
        "expiresAt": "2018-09-03T19:48:46.555Z",
        "isExternal": false,
        "verified": true,
        "aliases": [
            "tyyBofjOQzbTS5Q8Orif6YS1"
        ],
        "certs": [
            "zeit.rocks"
        ]
      }
    ]
  }`}</Code>
</Example>

### Add a new domain

<Endpoint method="POST" url="/v2/domains" />

Register a new domain name with <Now color="#000" /> for the authenticating
user. The field `serviceType` selects whether the domains is going to use
zeit.world DNS or an external nameserver. In the latter case a `CNAME/ALIAS`
record(s) are expected to point towards `alias.zeit.co`.

If an external nameserver is used the user must verify the domain name
by creating a TXT record for `_now` subdomain containing a
verification token provided as a POST result. After the record has
been created, the user may retry the same POST and the endpoint shall return
`verified: true`, if the domain was verified successfully.

#### Input

<InputTable>
  <Row>
    <BoldCell>name</BoldCell>
    <TypeCell>String</TypeCell>
    <BooleanCell status={true} />
    <Cell>The domain name you want to add.</Cell>
  </Row>
  <Row>
    <BoldCell>serviceType</BoldCell>
    <TypeCell>Enum</TypeCell>
    <BooleanCell status={false} />
    <Cell>
      <InlineCode>external</InlineCode> for{' '}
      <Link href="/docs/features/dns#adding-a-domain-using-external-nameservers">
        externally handled domain
      </Link>
      ; <InlineCode>zeit.world</InlineCode> for managed.
    </Cell>
  </Row>
</InputTable>

#### Output

<OutputTable>
  <Row>
    <BoldCell>uid</BoldCell>
    <TypeCell>ID</TypeCell>
    <Cell>The unique identifier of the domain.</Cell>
  </Row>
  <Row>
    <BoldCell>verified</BoldCell>
    <TypeCell>Boolean</TypeCell>
    <Cell>If the domain has the ownership verified.</Cell>
  </Row>
  <Row>
    <BoldCell>verifyToken</BoldCell>
    <TypeCell>String</TypeCell>
    <Cell>
      The{' '}
      <Link href="/docs/features/dns#adding-a-domain-using-external-nameservers">
        token
      </Link>{' '}
      required to verify the ownership of an external domain.
    </Cell>
  </Row>
  <Row>
    <BoldCell>created</BoldCell>
    <TypeCell>Date</TypeCell>
    <Cell>The date when the new domain was created.</Cell>
  </Row>
</OutputTable>

<Example>
  Example request adding a zeit.world domain:

<Request
  method="POST"
  url="https://api.zeit.co/v2/domains"
  headers={{
    Authorization: `Bearer ${
      props.testingToken ? props.testingToken.token : '$TOKEN'
    }`,
    'Content-Type': 'application/json'
  }}
  body={{
    name: 'zeit.rocks',
    serviceType: 'zeit.world'
  }}
/>

Successful (**200**) response:

<Code lang="json">{`{
    uid: "V0fra8eEgQwEpFhYG2vTzC3K",
    verified: true,
    created: "2016-09-23T11:53:38.600Z"
  }`}</Code>

Example request adding a unverified external domain:

<Request
  method="POST"
  url="https://api.zeit.co/v2/domains"
  headers={{
    Authorization: `Bearer ${
      props.testingToken ? props.testingToken.token : '$TOKEN'
    }`,
    'Content-Type': 'application/json'
  }}
  body={{
    name: 'awesome-now.us',
    serviceType: 'zeit.world'
  }}
/>

Successful (**200**) response:

<Code lang="json">{`{
    uid: "V0fra8eEgQwEpFhYG2vTzC3K",
    verified: false,
    verifyToken: "3f786850e387550fdab836ed7e6dc881de23001b",
    created: "2016-09-23T11:53:38.600Z"
  }`}</Code>
</Example>

### Remove a domain by name

<Endpoint method="DELETE" url="/v2/domains/:name" />

Delete a previously registered domain name from <Now color="#000" />.
Deleting a domain will automatically remove any associated aliases.

#### Output

<OutputTable>
  <Row>
    <BoldCell>uid</BoldCell>
    <TypeCell>ID</TypeCell>
    <Cell>The unique ID of the removed domain.</Cell>
  </Row>
</OutputTable>

<Example>
  Example request:

<Request
  method="DELETE"
  url="https://api.zeit.co/v2/domains/zeit.rocks"
  headers={{
    Authorization: `Bearer ${
      props.testingToken ? props.testingToken.token : '$TOKEN'
    }`
  }}
/>

Example successful (**200**) response:

<Code lang="json">{`{
    uid: "V0fra8eEgQwEpFhYG2vTzC3K"
  }`}</Code>
</Example>

### Check a domain availability

<Endpoint method="GET" url="/v2/domains/status?name" />

Check if a domain name _may_ be available to buy or not. The response is a JSON with the key `available` as a boolean.

#### Output

<OutputTable>
  <Row>
    <BoldCell>status</BoldCell>
    <TypeCell>Boolean</TypeCell>
    <Cell>If the domain is available or not.</Cell>
  </Row>
</OutputTable>

<Example>
  Example request:

<Request
  url="https://api.zeit.co/v2/domains/status?name=zeit.rocks"
  headers={{
    Authorization: `Bearer ${
      props.testingToken ? props.testingToken.token : '$TOKEN'
    }`
  }}
/>

Example successful (**200**) response:

<Code lang="json">{`{
    "status": false
  }`}</Code>
</Example>

### Check the price of a domain

<Endpoint method="GET" url="/v2/domains/price?name" />

Check the price to purchase a domain and how long a single purchase period is. The response is a JSON with the key `price` as a number (always an integer) and a key `period` as a number indicating the amount of years the domains could be hold before paying again.

#### Output

<OutputTable>
  <Row>
    <BoldCell>price</BoldCell>
    <TypeCell>Integer</TypeCell>
    <Cell>The domain price.</Cell>
  </Row>
  <Row>
    <BoldCell>period</BoldCell>
    <TypeCell>Integer</TypeCell>
    <Cell>The time period by which the domain is purchased.</Cell>
  </Row>
</OutputTable>

<Example>
  Example request:

<Request
  url="https://api.zeit.co/v2/domains/price?name=zeit.rocks"
  headers={{
    Authorization: `Bearer ${
      props.testingToken ? props.testingToken.token : '$TOKEN'
    }`
  }}
/>

Example successful (**200**) response:

<Code lang="json">{`{
    "price": 17,
    "period": 1
  }`}</Code>
</Example>

### Purchase a domain

<Endpoint method="POST" url="/v2/domains/buy" />

Purchase the specified domain, it receive the domain name as the key `name` inside the request body.

In case of a successful purchase the returns with code 200 and an empty body.

#### Input

<InputTable>
  <Row>
    <BoldCell>name</BoldCell>
    <TypeCell>String</TypeCell>
    <BooleanCell status={true} />
    <Cell>The domain name you want to purchase.</Cell>
  </Row>
  <Row>
    <BoldCell>expectedPrice</BoldCell>
    <TypeCell>Number</TypeCell>
    <BooleanCell status={false} />
    <Cell>The price you expect to be charged for the purchase.</Cell>
  </Row>
</InputTable>

<Example>
  Example request:

<Request
  method="POST"
  url="https://api.zeit.co/v2/domains/buy"
  headers={{
    Authorization: `Bearer ${
      props.testingtoken ? props.testingtoken.token : '$token'
    }`,
    'Content-Type': 'application/json'
  }}
  body={{
    name: 'zeit.rocks'
  }}
/>

Example failed **403** response:

<Code lang="json">{`{
    "error": {
      "code": "not_available",
      "message": "Domain is not available"
    }
  }`}</Code>
</Example>
